fix(extensions): make mandatory-hook dispatch contract self-contained by Quratulain-bilal · Pull Request #2901 · github/spec-kit

Quratulain-bilal · 2026-06-09T03:21:39Z

Problem

The EXECUTE_COMMAND: directive emitted for optional: false hooks is meant as a dispatch signal. In agent-direct
invocations (a slash command run inside Claude Code, Cursor, Codex, etc. — the default pattern for extension users),
nothing watches for it. The agent emits the directive, waits, and moves on — the hook never runs, and the failure is
completely silent.

This is the execution half of #2688: PR #2713 (v0.8.15) fixed the emission half (the directive now reliably appears in
agent output), but nothing dispatches it.

This implements Resolution Path 1 from the issue — the lowest-cost fix: make the contract self-contained so the agent
performs the dispatch itself.

Changes

format_hook_message() (src/specify_cli/extensions.py): after the EXECUTE_COMMAND: /
EXECUTE_COMMAND_INVOCATION: lines, the message now tells the agent the directive alone executes nothing, and it must
invoke the rendered hook command itself and wait for completion before continuing.
templates/commands/*.md (all 9 command templates): added the same dispatch-contract bullet after every
mandatory-hook block (pre- and post-execution, 18 sites), and tightened the Done When checklist — emitting
EXECUTE_COMMAND: alone does not count as dispatched.
extensions/EXTENSION-API-REFERENCE.md: documented the dispatch contract so extension authors don't assume an
external dispatcher will pick up the directive.

Backward compatibility

The EXECUTE_COMMAND: / EXECUTE_COMMAND_INVOCATION: directive lines are unchanged and still emitted. To be precise: I
could not find a code path in this repository that currently consumes the directive — HookExecutor.execute_hook()
exists but has no production callers, and the auto_execute_hooks setting is written as a default but never read for
dispatch. The directive is preserved for any external or future consumer, but nothing in-repo depends on it today, which
is consistent with the failure mode reported in #2730. Optional hooks are untouched: they remain a user-facing prompt
with no self-dispatch mandate.

Tests

test_mandatory_hook_message_instructs_agent_to_dispatch — the runtime hook message contains the self-dispatch
instruction with the rendered invocation.
test_optional_hook_message_has_no_dispatch_mandate — optional hooks stay advisory; no behavioral change.
test_bundled_templates_state_directive_dispatch_contract — every EXECUTE_COMMAND block in every bundled template
carries the contract bullet, so a future template edit can't silently regress agent-direct invocations back to
emit-and-stall.

Full tests/test_extensions.py suite passes (248 passed). The two pre-existing test_setup_tasks.py PowerShell-hint
failures reproduce on clean main and are unrelated to this change.

AI disclosure

This PR was authored with AI assistance (Claude Code) code changes, tests, and description under my direction and review.

mnriem

Thanks for the contribution. A couple of questions before we can move forward:

Orchestrator claim: The PR body references specify run and "CLI orchestrators that watch agent output" as existing consumers of the EXECUTE_COMMAND: directive. Can you point to the code path where this dispatch actually happens today? If no orchestrator currently consumes the directive, the backward-compatibility framing is misleading and the PR description should be corrected.
AI disclosure: Was this PR authored with AI assistance? If so, please disclose per contributing guidelines.

The underlying fix (agent self-dispatches mandatory hooks in agent-direct sessions) addresses a real problem, but the bar is high for sweeping template changes and we need confidence the framing accurately reflects the codebase.

Quratulain-bilal · 2026-06-09T16:09:56Z

closed this by accident while editing the description - reopened.

on the orchestrator question: you're right, I rechecked and couldn't find anything in the repo that actually consumes
EXECUTE_COMMAND today. execute_hook() has no production callers and auto_execute_hooks gets written as a default but
never read. I picked that framing up from the issue author's wording in #2730 without verifying it myself. fixed the PR
description.

and yes, this was built with AI assistance (Claude Code) - code, tests and description, reviewed by me. added the
disclosure to the PR body.

if the template changes are too broad I can cut it down to just the format_hook_message() change + tests and do the
templates as a follow-up.

Copilot

Pull request overview

This PR strengthens the extension mandatory-hook “dispatch contract” so agent-direct invocations (Claude Code / Cursor / Codex, etc.) don’t silently emit EXECUTE_COMMAND: without actually running the hook, by explicitly instructing the agent to self-dispatch and wait.

Changes:

Updates runtime hook messaging to explain that EXECUTE_COMMAND: is a signal (not a dispatcher) and that mandatory hooks must be invoked and awaited.
Updates all bundled command templates to embed the same dispatch-contract guidance and tightens “Done When” criteria.
Adds/extends tests to prevent regressions in both runtime messages and bundled templates.

Show a summary per file

File	Description
`src/specify_cli/extensions.py`	Extends mandatory-hook message text to instruct self-dispatch.
`templates/commands/analyze.md`	Adds dispatch-contract bullet after mandatory hook blocks.
`templates/commands/checklist.md`	Adds dispatch-contract bullet after mandatory hook blocks.
`templates/commands/clarify.md`	Adds dispatch-contract bullet after mandatory hook blocks and tightens Done When.
`templates/commands/constitution.md`	Adds dispatch-contract bullet after mandatory hook blocks.
`templates/commands/implement.md`	Adds dispatch-contract bullet after mandatory hook blocks and tightens Done When.
`templates/commands/plan.md`	Adds dispatch-contract bullet after mandatory hook blocks and tightens Done When.
`templates/commands/specify.md`	Adds dispatch-contract bullet after mandatory hook blocks and tightens Done When.
`templates/commands/tasks.md`	Adds dispatch-contract bullet after mandatory hook blocks and tightens Done When.
`templates/commands/taskstoissues.md`	Adds dispatch-contract bullet after mandatory hook blocks.
`extensions/EXTENSION-API-REFERENCE.md`	Documents the dispatch contract for extension authors.
`tests/test_extensions.py`	Adds tests for the runtime message contract and template coverage.

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Files reviewed: 12/12 changed files
Comments generated: 19

Copilot

Copilot's findings

Files reviewed: 12/12 changed files
Comments generated: 20

mnriem · 2026-06-09T23:01:08Z

Please address Copilot feedback

Copilot

Copilot's findings

Files reviewed: 12/12 changed files
Comments generated: 0 new

mnriem · 2026-06-11T12:33:16Z

Yes, the template changes are way too broad. We should look into a fix with a smaller surface

Quratulain-bilal · 2026-06-13T12:18:11Z

makes sense, agree it's too broad.

while trying to shrink it I found the reason it spread: format_hook_message() in extensions.py isn't actually reached at runtime its only caller is check_hooks_for_event(), which nothing in the CLI or agent path calls. the hook block is emitted by the agent following the command-template instructions (it reads .specify/extensions.yml and outputs the block itself), so the templates are where the behavior actually lives hence all 9.

two smaller options:
one line in the mandatory-hook instruction of each template, no example-block edits - still 9 files but a tiny diff each
or fix just plan as the pattern, then the rest in a follow-up

any preference on direction?

mnriem · 2026-06-16T13:54:26Z

Pick one and lets see how it looks

… directive In agent-direct invocations (a slash command run inside Claude Code, Cursor, etc.) nothing watches agent output for EXECUTE_COMMAND:, so a mandatory hook that is only emitted never runs and the failure is silent (github#2730). Add one line after each mandatory-hook block in the command templates instructing the agent to actually invoke the hook and wait for it before continuing. Minimal version of the earlier broad change, per maintainer feedback: example blocks are left untouched; only a single instruction line is added per mandatory-hook block. Fixes github#2730

Quratulain-bilal · 2026-06-17T06:06:02Z

went with option 1 - one instruction line after each mandatory-hook block, example blocks untouched. rebased on current main so the diff is clean: 9 files, 18 lines.

Quratulain-bilal requested a review from mnriem as a code owner June 9, 2026 03:21

Quratulain-bilal changed the title ~~fix(extensions): make mandatory-hook dispatch contract self-contained…~~ fix(extensions): make mandatory-hook dispatch contract self-contained Jun 9, 2026

Quratulain-bilal mentioned this pull request Jun 9, 2026

[Bug]: PR #2713's EXECUTE_COMMAND directive emits correctly but is never executed in pure-Claude-Code invocations #2730

Open

mnriem reviewed Jun 9, 2026

View reviewed changes

Quratulain-bilal closed this Jun 9, 2026

Quratulain-bilal reopened this Jun 9, 2026

mnriem requested a review from Copilot June 9, 2026 20:43

Copilot started reviewing on behalf of mnriem June 9, 2026 20:43 View session

Copilot AI reviewed Jun 9, 2026

View reviewed changes

mnriem requested a review from Copilot June 9, 2026 22:51

Copilot started reviewing on behalf of mnriem June 9, 2026 22:51 View session

Copilot AI reviewed Jun 9, 2026

View reviewed changes

mnriem requested a review from Copilot June 10, 2026 20:32

Copilot started reviewing on behalf of mnriem June 10, 2026 20:32 View session

Copilot AI reviewed Jun 10, 2026

View reviewed changes

Quratulain-bilal force-pushed the fix/hook-directive-dispatch-contract branch from 5339123 to aabc7c7 Compare June 17, 2026 05:48

mnriem self-requested a review June 17, 2026 12:31

Conversation

Quratulain-bilal commented Jun 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Problem

Changes

Backward compatibility

Tests

AI disclosure

Uh oh!

mnriem left a comment

Choose a reason for hiding this comment

Uh oh!

Quratulain-bilal commented Jun 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Copilot's findings

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot's findings

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mnriem commented Jun 9, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot's findings

Uh oh!

mnriem commented Jun 11, 2026

Uh oh!

Quratulain-bilal commented Jun 13, 2026

Uh oh!

mnriem commented Jun 16, 2026

Uh oh!

Quratulain-bilal commented Jun 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Quratulain-bilal commented Jun 9, 2026 •

edited

Loading

Quratulain-bilal commented Jun 9, 2026 •

edited

Loading